The ISC Bulletin Download Utility

The isc_downloader package provides a set of APIs to download a customized ISC catalogue from the ISC website (http://www.isc.ac.uk/iscbulletin/) using the Python command line.


In [ ]:
%matplotlib inline
import eqcat.isc_downloader as isc

Basic Usage

At first, an url-based catalogue request object should be created with:


In [ ]:
Cat1 = isc.ISCBulletinUrl()

The object contains a set of default parameters that can be listed with the merthod 'ListField'. A full description of each parameter and the list of available options can be found at http://www.isc.ac.uk/iscbulletin/search/webservices/.


In [ ]:
Cat1.ListFields()

Each parameter can then be modified with the method 'SetField'(particular care should be paid to the standard format of the different options). For example, the desired output format for the catalogue can be set to ISF with the following command:


In [ ]:
Cat1.SetField("OutputFormat","ISF")

As well, starting and ending time for the catalogue can be set with:


In [ ]:
Cat1.SetField("StartYear","2000")
Cat1.SetField("EndYear","2001")

or search area (Nepal in this example):


In [ ]:
Cat1.SetField('SearchAreaShape','RECT')
Cat1.SetField('RectangleBottomLatitude','23')
Cat1.SetField('RectangleTopLatitude','34')
Cat1.SetField('RectangleLeftLongitude','77')
Cat1.SetField('RectangleRightLongitude','91')

NOTE: When modified, optional parameters can be set back empty by using empty strings:


In [ ]:
Cat1.SetField("MinimumDepth","")

Finally, the catalogue can simply be downloaded with the command:


In [ ]:
Cat1.GetCatalogue()

And the result saved to disk:


In [ ]:
Cat1.WriteOutput("outputs/Example_ISF_Catalogue.isf")

The catalogue has been saved in an ascii file that can later be manipulated with the GEM catalogue tools.


In [ ]:
f = open("outputs/Example_ISF_Catalogue.isf", "r");
print(f.read())
f.close()

Saving/Loading Parameters

One might want to save the current settings on a separate file, to be used as reference or subsequently to download another catalogue. This can be done with the command:


In [ ]:
Cat1.SaveSettings("outputs/Example_Settings.par")

In [ ]:
f = open("outputs/Example_Settings.par", "r")
print(f.read())
f.close()

As well, the parameters in the parameter file can be loaded back into memory with:


In [ ]:
Cat2 = isc.ISCBulletinUrl()
Cat2.LoadSettings("outputs/Example_Settings.par")

Additional Formats

The ISC event catalogue can be saved in CSV format:


In [ ]:
Cat1.SetField("OutputFormat","CATCSV")
Cat1.GetCatalogue()
Cat1.WriteOutput("outputs/Example_CSV_Catalogue.csv")

In [ ]:
f = open("outputs/Example_CSV_Catalogue.csv", "r")
print(f.read())
f.close()

Catalogue of focal mechanisms is also available in CSV format:


In [ ]:
Cat1.SetField("OutputFormat","FMCSV")
Cat1.SetField("StartYear","2000")
Cat1.SetField("EndYear","2005")
Cat1.GetCatalogue()
Cat1.WriteOutput("outputs/Example_FM_Catalogue.csv")

In [ ]:
f = open("outputs/Example_FM_Catalogue.csv", "r")
print(f.read())
f.close()

Solving download issues

Note that sometimes the ISC server is heavily loaded and the http request might fail. In such a case it could be conveninent to use an alternate (mirror) server:


In [ ]:
Cat1.UseMirror()

Moreover, long time windows might produce a too large number of events, which cannot be downloaded in one block. The code gives the possibility to download the catalogue in separated blocks of a prescr ibed duration (using option SplitYears). The blocks are then automatically merged into a unique output:


In [ ]:
Cat1.SetField("OutputFormat","ISF")
Cat1.GetCatalogue(SplitYears=1)

Optionally, one can overwrite a previous download:


In [ ]:
Cat1.WriteOutput('outputs/Example_ISF_Catalogue_SPLIT.isf', OverWrite=True)